<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
		<title>M3Gen :: Lifecycle</title>
		<link rel="stylesheet" href="css/m3gen.css" type="text/css" />
	</head>
	<body>
		<h1>M3Gen :: Lifecycle</h1>
		<p>
		<h2>Creation of a ruleSetConfiguration</h2>
		<p>
			First a ruleSetConfiguration for the instance model to be used must be created.
		</p>
		<h3>Creation of a selectionModel</h3>
		<p>
			A seperate selectionModel for each objType in the instance model can be created containing the selection functions to be used by the
			ruleSets in the ruleSetConfiguration. This design choice enables reuse of selection functions across multiple ruleSetConfiguration.			
		</p>
		<h2>Creation of a m3gen.JsTreeModelGenerator instance</h2>
		<p>
			An instance of m3gen.JsTreeModelGenerator must be created, passing in the ruleSetConfiguration as a constructor argument.
			The global execution state (globalExecState) is also initialized. The globalExecState holds the current depth, the counters for each of the objTypes encountered, and the
			active ruleSet and activeObj (jsonObj) currently being used. It also holds the ruleSetConfiguration and any other important global states.¨
			The globalExecState must be passed to each constructor taking part in the execution process.
		</p>	
		<h2>Loading the instance model</h2>
		<p>
			When the JsTreeModelGenerator has been created and initialized, the json instance model must be loaded (fx via an ajax call or a static model can be used, usually for testing purposes).
			Note: Optionally the instance model can be passed as a constructor argument for m3gen.JsTreeModelGenerator alongside the ruleSetConfiguration.
		</p>
		<h2>Executing m3gen.JsTreeModelGenerator</h2>
		<p>
			Then JsTreeModelGenerator is executed using its execute() function. If the instance model has been set using the constructor, execute can be called with no arguments.
			Normally however, JsTreeModelGenerator is called with an instance model and optionally a nodeStateList, containing the lists of branch nodes to show in "open" and "closed" state.
			nodeStateList {open: [...], closed: [..]}.
		</p>		
		<h2>Parsing the instance model</h2>
		<p>
			During JsTreeModelGenerator execution the instance model is traversed and for each json object encountered 
			a new JsonObjParser is created, initialized with the ruleSetConfiguration and nodeStateList 
			and a objTypeCounter (for counting instances of a given objType, also used to generate unique Ids).
			The JsonObjParser is the executed with the jsonObj in order to parse the jsonObj and return a nodeObj model.
			The resulting nodeObj model can contain a hierarchy of nodeObj, including branchNodeObj.
			The nodeObj model is a canonical tree model. For use with jsTree it must be transformed to the specific jsTree model
			using the jsTreeNodeBuilder. The jsTreeNodeBuilder in turn uses specific content builders (see m3gen.JsTreeNodeContentBuilders.js)
			to create each of the content parts of the jsTree node.
		</p>		
		<h2>Generating the nodeObj model</h2>
		<h3>Selecting an active ruleSet</h3>
		<p>
			To generate the nodeObj model, JsonObjParser decides which objType the jsonObj is an instance of, using the selectObjType function 
			in the ruleSetConfiguration. If selectObjType can recognize the jsonObj as a known objType, the objType (a string identifier) is returned to be used as a key.
			JsonObjParser can then lookup a ruleSet with a key matching this objType key within the ruleSets object of ruleSetConfiguration.
			If a ruleSet is found for the jsonObj, it is set as the active ruleSet.			
		</p>
		<h3>Applying the active ruleSet</h3>
		<p>
			The active ruleSet can now be used on the jsonObj to generate a resulting nodeObj model.
			First the functions object within the ruleSet is used to see if there are selection functions
			for populating the nodeObj with content: id, attributes, state, data, metadata and languages.
			Then a NodeObjBuilder is created in order to build the nodeObj for the jsonObj. 
		</p>		
		<h3>Creating the nodeObj</h3>
		<p>
			First functions.selectId is called to generate an id for the nodeObj. In case useUniqueId is set 
			(in the ruleSet or globally for the ruleSetConfiguration) a uniqueId is generated, fx by using the
			objTypeCounter which was passed in at initialization of the JsonObjParser.
			Then the rest of the content of the nodeObj is created similarly using functions.selectLanguages, 
			functions.selectDataAttributes, functions.selectState etc.
			During this creation the active ruleSet and the ruleSetConfiguration is consulted in that order to provide defaults if necessary 
			(fx defaultState, iconsPath etc.).			
		</p>
		<h3>Creating nodeObj children</h3>
		<p>	
			If the ruleSet has a branchRules array, an attempt is made to create children of the nodeObj (A), 
			resulting in a hierarchical nodeObj model.	
			branchRules is traversed and for each branchRule an attempt is made to create a branch for the nodeObj.
			The branch can have its own container node (called a branchNodeObj) or be nested directly under the originating nodeObj (A).
		</p>
		<h3>Creating a branchNodeObj</h3>
		<p>	
			If the branchRule has a branchDef (branch definition), this definition is used to create the branchNodeObj.
			The branchDef has an id and title. The id is appended to the nodeObj id to create a unique id for the branchNodeObj 
			(note: each branchDef in the same branchRules must have unique ids!). The title is used as is, as the title of the branchNodeObj created.
			The branchDef can also have a branchType. This branchType is a key used for looking up a matching branchTypeRule in branchTypeRules of the ruleSetContainer.
			The branchTypeRule contains rules for setting the state and icon of the branchNodeObj.
		</p>
		<h3>Using child selectors</h3>
		<p>	
			The branchRule can also have a selectors object containing an array of selectors. 
			The selectors array is now traversed and each selector is applied to
			select new json objects to use as children for the current branch.
			If a branchNodeObject has been generated these children will be nested under this 'active' branchNodeObject, otherwise
			they will be nested directly under the originating nodeObj (A) (*).
			Each selector can either be a function or a path. In case its a selector function, this function is simply called with the
			current jsonObj as the argument, and the selector function must then know how to traverse this jsonObj to generate
			a list of children. In case the selector is a path, the current jsonPathMethod is retrieved (using first the setting in the ruleSet, and then defaulting upwards).
			The selector path is then resolved using an appropriate json path resolver (currently either 'xpath' or 'jpath') to return a list of children.
			Each child/list of children is appended into a child array for the branch. When all selectors have been resolved, this
			children list is then traversed, and each child is parsed individually by creating a new instance of JsonObjParser
			and executing it with the child as its main argument. the resulting nodeObj is then inserted appropriately (see * above).
			At some point the branch will terminate. To guard against enless cycles/recursion, a check is made in JsonObjParser as soon as an id is generated
			to see if this id has been visited before. If so parsing for this jsonObj is aborted.			
		</p>				
	</body>
</html>
